Troubleshooting Event Ingestion

​

Quick Diagnostic Checklist

• Feature exists and is active
• Event Name matches exactly (case-sensitive)
• External Customer ID exists in Flexprice
• API key is valid and has proper permissions
• Events are being transmitted to the correct endpoint
• Required fields are present in event payload
• Aggregation field exists in event properties (if required)
• Customer has an active subscription with the feature

​

Common Issues and Solutions

​

1. Events Not Appearing in Dashboard

​

A. Invalid Event Name

1. Go to Product Catalog → Features
2. Find your feature and note the exact Event Name
3. Compare with what you’re transmitting in events

// ❌ Wrong
{
  "event_name": "Model.Usage",
  "external_customer_id": "cust_123"
}

// ✅ Correct
{
  "event_name": "model.usage",
  "external_customer_id": "cust_123"
}

​

B. Customer Doesn’t Exist

1. Go to Customers section
2. Search for your external_customer_id
3. Verify the customer exists and is active

• Create the customer first, or
• Use the correct external_customer_id

​

C. Feature Not Active

1. Go to Product Catalog → Features
2. Find your feature
3. Verify status is “Active”

• Activate the feature if it’s archived

​

2. Wrong Aggregation Values

​

A. Aggregation Field Name Mismatch

1. Go to your feature configuration
2. Note the exact Aggregation Field name
3. Compare with your event properties

// Feature config: Aggregation Field = "credits"

// ❌ Wrong
{
  "event_name": "model.usage",
  "external_customer_id": "cust_123",
  "properties": {
    "tokens": 2  // Wrong field name
  }
}

// ✅ Correct
{
  "event_name": "model.usage",
  "external_customer_id": "cust_123",
  "properties": {
    "credits": 2  // Correct field name
  }
}

​

B. Wrong Data Type

• Numeric aggregations (SUM, AVERAGE, SUM WITH MULTIPLIER, MAX, WEIGHTED SUM) require numbers
• COUNT UNIQUE can use strings or numbers
• LATEST can use strings or numbers
• COUNT doesn’t use properties

// ❌ Wrong (for Sum aggregation)
{
  "properties": {
    "credits": "2"  // String instead of number
  }
}

// ✅ Correct
{
  "properties": {
    "credits": 2  // Number
  }
}

​

C. Missing Properties

• Every event must include the aggregation field
• Check for typos in property names

// ❌ Wrong (missing properties for Sum aggregation)
{
  "event_name": "model.usage",
  "external_customer_id": "cust_123"
  // Missing properties object
}

// ✅ Correct
{
  "event_name": "model.usage",
  "external_customer_id": "cust_123",
  "properties": {
    "credits": 2
  }
}

​

3. No Charges in Billing

​

A. Feature Not in Plan

1. Go to Product Catalog → Plans
2. Find the plan your customer is subscribed to
3. Verify the feature is included

• Add the feature to the plan with appropriate pricing

​

B. Customer Not Subscribed

1. Go to Customers → Find your customer
2. Check subscription status
3. Verify the subscription includes the feature

• Create a subscription for the customer
• Ensure the subscription includes the feature

​

C. Usage Below Free Tier

1. Review plan configuration
2. Check free tier settings
3. Verify usage quantities

• Adjust free tier limits if needed
• Transmit more usage to exceed free tier

​

D. Wrong Billing Period

1. Review subscription billing cycle
2. Check event timestamps
3. Verify billing period dates

• Wait for the correct billing period
• Check upcoming invoices for the right period

​

4. API Errors

​

A. 400 Bad Request

• Missing required fields
• Invalid JSON format
• Invalid field values

# Check your payload
curl -v --request POST \
  --url https://api.cloud.flexprice.io/v1/events \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <your_api_key>' \
  --data '{
    "event_name": "model.usage",
    "external_customer_id": "cust_123",
    "properties": {
      "credits": 2
    }
  }'

// ❌ Missing required field
{
  "external_customer_id": "cust_123"
  // Missing event_name
}

// ✅ Complete payload
{
  "event_name": "model.usage",
  "external_customer_id": "cust_123",
  "properties": {
    "credits": 2
  }
}

​

B. 401 Unauthorized

1. Verify your API key is correct
2. Check API key permissions
3. Ensure the key is active

​

C. 429 Too Many Requests

• Implement exponential backoff
• Use bulk events for high volume
• Reduce request frequency

​

5. Unexpected Usage Resets

​

A. Wrong Usage Reset Setting

1. Go to your feature configuration
2. Review Usage Reset setting:
   • Periodic: Resets each billing cycle
   • Cumulative: Keeps growing

• Change Usage Reset setting if needed
• Note: This may require creating a new feature

​

B. Subscription Changes

1. Review subscription history
2. Check for plan changes
3. Verify billing cycle alignment

​

6. Duplicate Events

• Retrying failed requests
• Multiple event sources
• Application bugs

• Use event_id for idempotency
• Implement proper retry logic
• Check for duplicate event sources

​

Systematic Debugging Approach

​

Step 1: Verify Event Ingestion

1. Send a test event
2. Check API response (should be 202 Accepted)
3. Look for the event in Events dashboard
4. Verify the payload is correct

​

Step 2: Check Feature Configuration

1. Confirm Event Name matches exactly
2. Verify Aggregation Function is correct
3. Check Aggregation Field name
4. Review Usage Reset setting

​

Step 3: Validate Customer Setup

1. Ensure customer exists
2. Check external_customer_id matches
3. Verify subscription is active
4. Confirm plan includes the feature

​

Step 4: Review Billing Configuration

1. Check plan pricing settings
2. Verify free tier configuration
3. Review billing cycle dates
4. Check upcoming invoices

​

Debugging Tools

​

Event Debugger

1. Go to Usage Tracking → Event Debugger
2. Monitor events as they’re processed
3. Look for errors or warnings

​

Events Dashboard

1. Event processing status
2. Complete event payloads
3. Timestamp information
4. Customer mapping

​

Query Tool

1. View aggregated usage
2. Check billing period alignment
3. Verify aggregation calculations

​

Testing Your Fix

1. Send Test Events
   Copy

   curl --request POST \
     --url https://api.cloud.flexprice.io/v1/events \
     --header 'Content-Type: application/json' \
     --header 'x-api-key: <your_api_key>' \
     --data '{
       "event_name": "model.usage",
       "external_customer_id": "cust-test-customer",
       "properties": {
         "credits": 1
       }
     }'
   

2. Verify Event Processing
   • Check Events dashboard
   • Confirm payload is correct
   • Verify aggregation values
3. Check Billing Impact
   • Review upcoming invoices
   • Confirm charges appear correctly
   • Verify amounts are accurate

​

Prevention Best Practices

​

1. Test Before Production

• Always test with a small number of events
• Use test customers and features
• Verify the complete flow end-to-end

​

2. Monitor Regularly

• Check Events dashboard daily
• Review usage patterns weekly
• Monitor billing accuracy monthly

​

3. Use Consistent Naming

• Standardize Event Names across your system
• Use consistent external_customer_id format
• Follow naming conventions for properties

​

4. Implement Proper Error Handling

• Handle API errors gracefully
• Implement retry logic with backoff
• Log failed events for debugging

​

5. Document Your Setup

• Keep records of feature configurations
• Document Event Names and field mappings
• Maintain customer ID mappings

​

Getting Additional Help

1. Gather Information:
   • Event payload examples
   • Feature configuration screenshots
   • Error messages and timestamps
   • Customer and subscription details
2. Check Documentation:
   • Review relevant guides
   • Check API reference
   • Look for similar issues
3. Contact Support:
   • Provide specific error details
   • Include relevant screenshots
   • Share event examples (with sensitive data removed)

​

Common Configuration Examples

​

API Usage Tracking

// Feature: API Calls (Count)
{
  "event_name": "api.calls",
  "external_customer_id": "cust_123"
}

// Feature: API Usage (Sum of tokens)
{
  "event_name": "api.usage",
  "external_customer_id": "cust_123",
  "properties": {
    "tokens": 150
  }
}

​

Storage Usage

// Feature: Storage (Sum of GB)
{
  "event_name": "storage.usage",
  "external_customer_id": "cust_123",
  "properties": {
    "gb": 1.5
  }
}

​

User Activity

// Feature: Active Users (Unique Count)
{
  "event_name": "active.users",
  "external_customer_id": "cust_123",
  "properties": {
    "user_id": "user_456"
  }
}